<script type="text/javascript"
     src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
</script>

<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<head>
    <link rel="stylesheet" href="stylesheet_TMATS.css">
</head>

<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<title>
    T-MATS: Help for Steady State Newton Raphson Solver with Jacobian Calculator
        Library Block
</title>

<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<body>
    <h1>
      T-MATS: Steady State Newton Raphson Solver with Jacobian Calculator Library Block
    </h1>
<hr>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<div class="purpose">
        Purpose
</div>

<p>
    This block is used to supply the inputs to iteratively drive the outputs
    of a system to zero by using a T-MATS Newton Raphson Solver block in combination
    with a T-MATS Jacobian Calculator block. The help files for these blocks can be
    accessed by the following links:
    <ul>
        <li><a href="TMATS_Library/TMATS_Support/NumMthd_TMATS_NRS.html">
        Newton Raphson Solver block</a>
        <li><a href="TMATS_Library/TMATS_Support/NumMthd_TMATS_JC.html">
        Jacobian Calculator block</a>
    </ul>
</p>

<br>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<div class="background">
        Background
</div>

<p>
    This block will perform its calculations in three steps:
    <ol>
        <li>Jacobian Calculator sends perturbations to the plant model that
        then calculates the plant Jacobian based on the system response.
        <li>Newton Raphson Solver will use the inverse of the Jacobian to
        iteratively step the system toward solution.
        <li> Once the solution has satisfied the conditions, the Newton
        Raphson Solver is shut off.
    </ol>
</p>
<p>
    Since this block uses the simulink simulation time step as the iteration steps for
    Jacobian calculation and Newton Raphson operation, the simulation time step should be set
    to allow for enough steps to solve the optimization. To this end the simulation should be
    set to use a fixed time step and the simulation stop time should be set to allow sufficient steps.
</p>

<br>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<div class="instructions">
        Instructions
</div>

<p>
    To use this block:
    <ul>
        <li> Connect the input function to the corresponding place on the block.
        <li> Connect the input command to enable the block.
        <li> Connect the outputs to the next blocks in the simulation.
        <li> Verify the the simulation is set to use a fixed time step and has a reasonable simulation stop time.
        <li> Double click the block and specify the following:
        <ul>
            <li>Jacobian perturbation size
            <li>Newton Raphson initial conditions
            <li>Newton Raphson step size limits
            <li>Newton Raphson max/min limits
            <li>Newton Raphson attempts before Jacobian recalculation
            <li>Iteration condition limits
        </ul>
    </ul>
</p>
<p>
    For more information about each input, output, and mask variable, see
    the tables below.
</p>

<br><hr><br>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<div class="inputs">
        SS Newton Raphson w Jacobian Calculator Inputs
</div>

<table>
    <tr><th> Input </th><th>Description</th></tr>
    <tr><td>Enable</td><td>Enable Solver</td></tr>
    <tr><td>f(x)</td><td>Output of plant to be solved for, (mx1 vector
    consisting of all plant outputs or dependents)</td></tr>
</table>

<br><br>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<div class="outputs">
        SS Newton Raphson w Jacobian Calculator Outputs
</div>

<table>
    <tr><th> Output </th><th> Description </th></tr>
    <tr><td>X</td><td>Input to plant to be solved for, (mx1 vector consisting
                        of all plant inputs or independents)
    <br> Initial value will be set as the initial conditions</td></tr>
    <tr><td>S_Data</td><td>Solver internal calculation data, 3x1 vector including:
            <br>- Converged - Solver Conditions have been met
            <br>- J - Calculated Jacobian Matrix
            <br>- JacFailed - Jacobian inversion fault (0 - no fault, 1 - fault)</td></tr>
</table>

<br><br>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<div class="maskvars">
        SS Newton Raphson w Jacobian Calculator Mask Variables
</div>

<table>
    <tr><th> Mask Variable </th><th> Description </th></tr>
    <tr><td>SJac_Per_M</td><td>Jacobian Perturbation size (nxm), where m is
    the number of inputs and n is the number of times each input is perturbed</td></tr>
    <tr><td>SNR_IC_M</td><td>Newton Raphson Initial Conditions (mx1)</td></tr>
    <tr><td>SNR_DX_M</td><td>Newton Raphson step size (dx) limiter (%)(1x1)</td></tr>
    <tr><td>SNR_Mx_M</td><td>Newton Raphson max value limit(1x1 or mx1)</td></tr>
    <tr><td>SNR_Mn_M</td><td>Newton Raphson min value limit (1x1 or mx1)</td></tr>
    <tr><td>SJacobianAttempts_M</td><td>Newton Raphson attempts before the Jacobian recalculation (1x1)</td></tr>
    <tr><td>Cond_Limits_M</td><td>Iteration Conditions Limits (mx1 or 1x1)</td></tr>
</table>


<br><hr><br>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->

<div class = "errors">
    Potential Errors
</div>
<p>
When using this block, you may receive one of the following errors/warnings. The table
below lists the errors/warnings that you may see and the reason why it is being displayed.
</p>
<table>
    <tr><th> Error/Warning </th><th>Description</th></tr>
    <tr><td>Jacobian can not be inverted.</td><td>The resulting Jacobian matrix
is singular (determinant = 0) and cannot be inverted.</td></tr>
</table>
<p>
When using this block, there is also a possibility that the Newton Raphson
Solver will not converge to a solution. This can happen for a variety of
reasons, as listed below:
<ul>
    <li>The initial guess (initial condition) was not close enough to the
    desired root. This can cause the system to either diverge completely or converge
    on a secondary root of the function.
    <li>The derivative of the function is not well behaved, causing the system
    to overshoot the correct root and diverge.
    <li>The initial guess (or a resulting value after one or more iterations)
    is a point in the function for which the derivative is zero. This results
    in a divide-by-zero situation, and an error occurs.
    <li>The results of the solver hit one of the user-specified limits.
</ul>

<br><br>
<!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
</body>